{/* Copyright 2025 Adobe. All rights reserved.
This file is licensed to you under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License. You may obtain a copy
of the License at http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under
the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
OF ANY KIND, either express or implied. See the License for the specific language
governing permissions and limitations under the License. */}

import {Layout} from '../../src/Layout';
export default Layout;
import {FunctionAPI} from '../../src/FunctionAPI';
import {InterfaceType} from '../../src/types';
import docs from 'docs:@react-aria/i18n';
import typeDocs from 'docs:@internationalized/number';

export const section = 'Utilities';
export const description = 'Wraps Intl.NumberFormat and formats numbers for the current locale.';

# useNumberFormatter

<PageDescription>{docs.exports.useNumberFormatter.description}</PageDescription>

## Introduction

`useNumberFormatter` wraps a builtin browser [Intl.NumberFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat)
object to provide a React Hook that integrates with the i18n system in React Aria. It handles formatting numbers for the current locale,
updating when the locale changes, and caching of number formatters for performance. See the
[Intl.NumberFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) docs for
information on formatting options.

## Example

This example displays a currency value for two locales: USA, and Germany. Two instances of the `Currency` component are rendered,
using the [I18nProvider](I18nProvider) to specify the locale to display.

```tsx render
'use client';
import {I18nProvider, useNumberFormatter} from 'react-aria';

function Currency({value, currency}) {
  let formatter = useNumberFormatter({
    style: 'currency',
    currency,
    minimumFractionDigits: 0
  });

  return (
    <p>{formatter.format(value)}</p>
  );
}

<>
  <I18nProvider locale="en-US">
    <Currency value={125000} currency="USD" />
  </I18nProvider>
  <I18nProvider locale="de-DE">
    <Currency value={350000} currency="EUR" />
  </I18nProvider>
</>
```

## API

<FunctionAPI function={docs.exports.useNumberFormatter} links={docs.links} />

### NumberFormatOptions

<InterfaceType {...typeDocs.exports.NumberFormatOptions} />
